/**
  * @addtogroup nvm_queue_ports
  * nvm_queue_ports
  *
  * @brief
  *
  * @code  使用说明示例
    // 导入队列相关配置所需参数
    NvmQueuePortsCreate(queue_info, queue_state, nf_event, queue_count);
    // 初始化
    NvmQueuePortsInit();
    // 去初始化
    NvmQueuePortsFini();

  * @endcode
  * @{
  * @file         nvm_queue_ports.h(单片机平台ec800)
  * @brief
  * @note
  * @author       zhengganle
  * @date         2022-10-21
  * @version      1.0
  *
  * @par          修改日志
  * <table>
  * <tr><th>Date        <th>Version          <th>Author                        <th>Description
  * <tr><td>2022-10-21  <td>1.0              <td>ganle.zheng@hopechart.com     <td>创建初始版本
  * @copyright    杭州鸿泉物联网技术股份有限公司
  */
#ifndef _NVM_QUEUE_PORTS_H_
#define _NVM_QUEUE_PORTS_H_

#include "ofc/ofc_types.h"

#ifdef __cplusplus
extern "C" {
#endif

/*
 * nfqueue队列信息
 */
typedef struct TNvmQueueInfoTag TNvmQueueInfo;
struct TNvmQueueInfoTag
{
    UInt8 nor_flash_num;         ///< 所在nor_flash区号
    //Int32 page_start_;           ///< 起始位置
    UInt64 physical_offset;       ///< 物理偏移，应为某一页的起始地址，作为分区的起始，单位：字节
    Int32 page_count_;           ///< 页数(每页4K 也就是4096字节, 每次偏移量不得大于4096)
    Bool  read_only_;            ///< 只读属性
};

/**
 * 读取数据的函数指针
 * @param user_param    用户自定义参数对象
 * @param queue_info    对应队列信息
 * @param page_no       页号, 参数值范围: [0..page_count-1]
 * @param offset        页内的偏移地址
 * @param data          读取数据的缓冲区地址
 * @param size          读取数据的尺寸, 注: offset + size < pagesize
 * @return 错误码参考THccMidNvmErrorCodeEnumTag
 */
typedef Int32 (*TNvmQueueNFRead)(void* user_param, TNvmQueueInfo *queue_info, int page_no, int offset, void* data, int size);

/**
 * 写入数据的函数指针
 * @param user_param    用户自定义参数对象
 * @param queue_info    对应队列信息
 * @param page_no       页号, 参数值范围: [0..page_count-1]
 * @param offset        页内的偏移地址
 * @param data          读取数据的缓冲区地址
 * @param size          读取数据的尺寸, 注: offset + size < pagesize
 * @return 错误码参考THccMidNvmErrorCodeEnumTag
 */
typedef Int32 (*TNvmQueueNFWrite)(void* user_param, TNvmQueueInfo *queue_info, int page_no, int offset, const void* data, int size);

/**
 * 擦除页数据的函数指针
 * @param user_param    用户自定义参数对象
 * @param queue_info    对应队列信息
 * @param page_no       页号, 参数值范围: [0..page_count-1]
 * @return 错误码参考THccMidNvmErrorCodeEnumTag
 */
typedef Int32 (*TNvmQueueNFErase)(void* user_param, TNvmQueueInfo *queue_info, int page_no);

/**
 * 用户自定义回调事件
 */
typedef struct TNvmQueueNFEventTag TNvmQueueNFEvent;
struct TNvmQueueNFEventTag
{
    // 使用自定义回调时需加锁
    TNvmQueueNFRead do_read;
    TNvmQueueNFWrite do_write;
    TNvmQueueNFErase do_erase;
};

/*
 * 队列状态
 */
typedef struct TNvmQueueStateTag TNvmQueueState;
struct TNvmQueueStateTag
{
    Int32 queue_handle_;    ///< NFQ 句柄
    Bool  is_opened_;       ///< 队列已经打开
};

/**
 * 队列端口配置初始化
 * @param queue_info: 传入的队列信息
 * @param queue_state: 队列状态
 * @param queue_count: 队列个数
 * @param event: 自定义回调事件(事件均不能为空)
 * @param user_param:用户自定义参数
 * @return kHccMidNvmSuccess:成功 kHccMidNvmFilure:失败
 */
Int32 NvmQueuePortsInit(const TNvmQueueInfo *queue_info, TNvmQueueState *queue_state, UInt32 queue_count, TNvmQueueNFEvent *event, void* user_param);

void NvmQueuePortsFini(void);

/**
 * 队列ID是否合法
 * @param queue_id: 队列索引ID
 * @return True:成功 False:失败
 */
Bool NvmQueuePortsVaildQueueId(UInt16 queue_id);

/**
 * 获取消息队列对象状态(内部判断ID是否合法)
 * @param queue_id: 队列索引ID
 * @return NULL:失败
 */
TNvmQueueState *NvmQueuePortsGetQueueState(UInt16 queue_id);

/**
 * 获取消息队列对象信息(内部判断ID是否合法)
 * @param queue_id: 队列索引ID
 * @return NULL:失败
 */
TNvmQueueInfo *NvmQueuePortsGetQueueInfo(UInt16 queue_id);

#ifdef __cplusplus
} // extern "C" {
#endif

#endif    // _NVM_QUEUE_PORTS_H_

/**
 * @}
 */


